<!DOCTYPE html>

































































<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="shortcut icon" type="image/x-icon" href="../../../favicon.ico" />
<title>Creating a Search Interface | Android Developers</title>
<link href="../../../assets/android-developer-docs-devguide.css" rel="stylesheet" type="text/css" />
<script src="../../../assets/search_autocomplete.js" type="text/javascript"></script>
<script src="../../../assets/jquery-resizable.min.js" type="text/javascript"></script>
<script src="../../../assets/android-developer-docs.js" type="text/javascript"></script>
<script src="../../../assets/prettify.js" type="text/javascript"></script>
<script type="text/javascript">
  setToRoot("../../../");
</script>
<noscript>
  <style type="text/css">
    html,body{overflow:auto;}
    #body-content{position:relative; top:0;}
    #doc-content{overflow:visible;border-left:3px solid #666;}
    #side-nav{padding:0;}
    #side-nav .toggle-list ul {display:block;}
    #resize-packages-nav{border-bottom:3px solid #666;}
  </style>
</noscript>
</head>
<body class="gc-documentation">

  <div id="header">
      <div id="headerLeft">
          <a href="../../../index.html" tabindex="-1"><img
              src="../../../assets/images/bg_logo.png" alt="Android Developers" /></a>
          <ul id="header-tabs" class="guide">
    
	<li id="home-link"><a href="../../../offline.html">
	
		<span class="en">Home</span>
		<span style="display:none" class="de">Startseite</span>
		<span style="display:none" class="es"></span>
		<span style="display:none" class="fr"></span>
		<span style="display:none" class="it"></span>
		<span style="display:none" class="ja">ホーム</span>
		<span style="display:none" class="zh-CN">主页</span>
		<span style="display:none" class="zh-TW">首頁</span>
	
	</a></li>
	<li id="sdk-link"><a href="../../../sdk/index.html">
		<span class="en">SDK</span>
	</a></li>
	<li id="guide-link"><a href="../../../guide/index.html" onClick="return loadLast('guide')">
	
		<span class="en">Dev Guide</span>
		<span style="display:none" class="de">Handbuch</span>
		<span style="display:none" class="es">Guía</span>
		<span style="display:none" class="fr">Guide</span>
		<span style="display:none" class="it">Guida</span>
		<span style="display:none" class="ja">開発ガイド</span>
		<span style="display:none" class="zh-CN">开发人员指南</span>
		<span style="display:none" class="zh-TW">開發指南</span>
	
	</a></li>
	<li id="reference-link"><a href="../../../reference/packages.html" onClick="return loadLast('reference')">
	
		<span class="en">Reference</span>
		<span style="display:none" class="de">Referenz</span>
		<span style="display:none" class="es">Referencia</span>
		<span style="display:none" class="fr">Référence</span>
		<span style="display:none" class="it">Riferimento</span>
		<span style="display:none" class="ja">リファレンス</span>
		<span style="display:none" class="zh-CN">参考</span>
		<span style="display:none" class="zh-TW">參考資料</span>
	
	</a></li>
	<li id="resources-link"><a href="../../../resources/index.html" onClick="return loadLast('resources')">
	
		<span class="en">Resources</span>
		<span style="display:none" class="de"></span>
		<span style="display:none" class="es"></span>
		<span style="display:none" class="fr"></span>
		<span style="display:none" class="it"></span>
    		<span style="display:none" class="ja"></span>
		<span style="display:none" class="zh-CN"></span>
		<span style="display:none" class="zh-TW"></span>
	
	</a></li>
	<li id="videos-link"><a href="../../../videos/index.html" onClick="return loadLast('videos')">
	
		<span class="en">Videos</span>
		<span style="display:none" class="de"></span>
		<span style="display:none" class="es"></span>
		<span style="display:none" class="fr"></span>
		<span style="display:none" class="it"></span>
		<span style="display:none" class="ja">ビデオ</span>
		<span style="display:none" class="zh-CN"></span>
		<span style="display:none" class="zh-TW"></span>
	
	</a></li>
	<li><a href="http://android-developers.blogspot.com" onClick="return requestAppendHL(this.href)">
	
		<span class="en">Blog</span>
		<span style="display:none" class="de"></span>
		<span style="display:none" class="es"></span>
		<span style="display:none" class="fr"></span>
		<span style="display:none" class="it"></span>
		<span style="display:none" class="ja">ブログ</span>
		<span style="display:none" class="zh-CN">博客</span>
		<span style="display:none" class="zh-TW">網誌</span>
	
	</a></li>


     
</ul>
     
      </div>
      <div id="headerRight">
          <div id="headerLinks">
          
          <a href="http://www.android.com">Android.com</a>
          </div>
  <div id="search" >
      <div id="searchForm">
          <form accept-charset="utf-8" class="gsc-search-box" 
                onsubmit="return submit_search()">
            <table class="gsc-search-box" cellpadding="0" cellspacing="0"><tbody>
                <tr>
                  <td class="gsc-input">
                    <input id="search_autocomplete" class="gsc-input" type="text" size="33" autocomplete="off"
                      title="search developer docs" name="q"
                      value="search developer docs"
                      onFocus="search_focus_changed(this, true)"
                      onBlur="search_focus_changed(this, false)"
                      onkeydown="return search_changed(event, true, '../../../')"
                      onkeyup="return search_changed(event, false, '../../../')" />
                  <div id="search_filtered_div" class="no-display">
                      <table id="search_filtered" cellspacing=0>
                      </table>
                  </div>
                  </td>
                  <td class="gsc-search-button">
                    <input type="submit" value="Search" title="search" id="search-button" class="gsc-search-button" />
                  </td>
                  <td class="gsc-clear-button">
                    <div title="clear results" class="gsc-clear-button">&nbsp;</div>
                  </td>
                </tr></tbody>
              </table>
          </form>
      </div><!-- searchForm -->
  </div><!-- search -->
      </div><!-- headerRight -->
      <script type="text/javascript">
        <!--  
        changeTabLang(getLangPref());
        //-->
      </script>
  </div><!-- header -->

  <div class="g-section g-tpl-240" id="body-content">
    <div class="g-unit g-first" id="side-nav">
      <div id="devdoc-nav">
<ul>

  <li>
    <h2><span class="en">Android Basics</span>
        <span class="de" style="display:none">Einführung in Android</span>
        <span class="es" style="display:none">Información básica sobre Android</span>
        <span class="fr" style="display:none">Présentation d'Android</span>
        <span class="it" style="display:none">Nozioni di base su Android</span>
        <span class="ja" style="display:none">Android の基本</span>
        <span class="zh-CN" style="display:none">Android 基础知识</span>
        <span class="zh-TW" style="display:none">Android 簡介</span>
    </h2>
    <ul>
      <li><a href="../../../guide/basics/what-is-android.html">
        <span class="en">What Is Android?</span>
        <span class="de" style="display:none">Was ist Android?</span>
        <span class="es" style="display:none">¿Qué es Android?</span>
        <span class="fr" style="display:none">Qu'est-ce qu'Android&nbsp;?</span>
        <span class="it" style="display:none">Che cos'è Android?</span>
        <span class="ja" style="display:none">Android とは</span>
        <span class="zh-CN" style="display:none">Android 是什么？</span>
        <span class="zh-TW" style="display:none">什麼是 Android？</span>
          </a></li>
      <li><a href="../../../guide/topics/fundamentals.html">
        <span class="en">Application Fundamentals</span>
        <span class="de" style="display:none">Anwendungsgrundlagen</span>
        <span class="es" style="display:none">Fundamentos de las aplicaciones</span>
        <span class="fr" style="display:none">Principes de base des applications</span>
        <span class="it" style="display:none">Concetti fondamentali sulle applicazioni</span>
        <span class="ja" style="display:none">開発の基礎</span>
        <span class="zh-CN" style="display:none">应用程序基础</span>
        <span class="zh-TW" style="display:none">應用程式基本原理</span>
      </a></li>

  <!--  <li><a style="color:gray;">The Android SDK</a></li> -->
  <!--  <li><a style="color:gray;">Walkthrough for Developers</a></li> -->
      <!-- quick overview of what it's like to develop on Android -->
    </ul>
  </li>

  <li>
    <h2>
      <span class="en">Framework Topics</span>
      <span class="de" style="display:none">Framework-Themen</span>
      <span class="es" style="display:none">Temas sobre el framework</span>
      <span class="fr" style="display:none">Thèmes relatifs au framework</span>
      <span class="it" style="display:none">Argomenti relativi al framework</span>
      <span class="ja" style="display:none">フレームワーク トピック</span>
      <span class="zh-CN" style="display:none">框架主题</span>
      <span class="zh-TW" style="display:none">架構主題</span>
    </h2>
    <ul>
      <li class="toggle-list">
        <div><a href="../../../guide/topics/fundamentals/activities.html">
          <span class="en">Activities</span>
        </a></div>
        <ul>
          <li><a href="../../../guide/topics/fundamentals/fragments.html">
            <span class="en">Fragments</span>
          </a></li>
          <li><a href="../../../guide/topics/fundamentals/loaders.html">
            <span class="en">Loaders</span>
          </a></li>
          <li><a href="../../../guide/topics/fundamentals/tasks-and-back-stack.html">
            <span class="en">Tasks and Back Stack</span></a></li>
        </ul>
      </li>
      <li class="toggle-list">
        <div><a href="../../../guide/topics/fundamentals/services.html">
          <span class="en">Services</span>
        </a></div>
        <ul>
          <li><a href="../../../guide/topics/fundamentals/bound-services.html">
            <span class="en">Bound Services</span>
          </a></li>
        </ul>
      </li>
      <li><a href="../../../guide/topics/providers/content-providers.html">
            <span class="en">Content Providers</span>
          </a></li>
      <li><a href="../../../guide/topics/intents/intents-filters.html">
            <span class="en">Intents and Intent Filters</span>
          </a></li>
      <li><a href="../../../guide/topics/fundamentals/processes-and-threads.html">
            <span class="en">Processes and Threads</span>
          </a></li>
    </ul>


    <ul>
      <li class="toggle-list">
        <div><a href="../../../guide/topics/ui/index.html">
            <span class="en">User Interface</span>
          </a></div>
        <ul>
          <li><a href="../../../guide/topics/ui/declaring-layout.html">
               <span class="en">XML Layouts</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/ui-events.html">
                <span class="en">Input Events</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/menus.html">
               <span class="en">Menus</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/actionbar.html">
               <span class="en">Action Bar</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/dialogs.html">
                <span class="en">Dialogs</span>
              </a></li>
          <li class="toggle-list">
            <div><a href="../../../guide/topics/ui/notifiers/index.html">
                <span class="en">Notifications</span>
            </a></div>
            <ul>
              <li><a href="../../../guide/topics/ui/notifiers/toasts.html">
                <span class="en">Toast Notifications</span>
              </a></li>
              <li><a href="../../../guide/topics/ui/notifiers/notifications.html">
                <span class="en">Status Bar Notifications</span>
              </a></li>
            </ul>
          </li>
          <li><a href="../../../guide/topics/ui/drag-drop.html">
                <span class="en">Drag and Drop</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/themes.html">
                <span class="en">Styles and Themes</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/custom-components.html">
                <span class="en">Custom Components</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/binding.html">
                <span class="en">Binding to Data with AdapterView</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/layout-objects.html">
                <span class="en">Common Layout Objects</span>
              </a></li>
          <li><a href="../../../guide/topics/ui/how-android-draws.html">
                <span class="en">How Android Draws Views</span>
              </a></li>
        </ul>
      </li><!-- end of User Interface -->

      <li class="toggle-list">
        <div><a href="../../../guide/topics/resources/index.html">
               <span class="en">Application Resources</span>
             </a></div>
        <ul>
          <li><a href="../../../guide/topics/resources/providing-resources.html">
                <span class="en">Providing Resources</span>
              </a></li>
          <li><a href="../../../guide/topics/resources/accessing-resources.html">
                <span class="en">Accessing Resources</span>
              </a></li>
          <li><a href="../../../guide/topics/resources/runtime-changes.html">
                <span class="en">Handling Runtime Changes</span>
              </a></li>
          <li><a href="../../../guide/topics/resources/localization.html">
                <span class="en">Localization</span>
              </a></li>
          <li class="toggle-list">
            <div><a href="../../../guide/topics/resources/available-resources.html">
              <span class="en">Resource Types</span>
            </a></div>
            <ul>
              <li><a href="../../../guide/topics/resources/animation-resource.html">Animation</a></li>
              <li><a href="../../../guide/topics/resources/color-list-resource.html">Color State List</a></li>
              <li><a href="../../../guide/topics/resources/drawable-resource.html">Drawable</a></li>
              <li><a href="../../../guide/topics/resources/layout-resource.html">Layout</a></li>
              <li><a href="../../../guide/topics/resources/menu-resource.html">Menu</a></li>
              <li><a href="../../../guide/topics/resources/string-resource.html">String</a></li>
              <li><a href="../../../guide/topics/resources/style-resource.html">Style</a></li>
              <li><a href="../../../guide/topics/resources/more-resources.html">More Types</a></li>
            </ul>
          </li><!-- end of resource types -->
        </ul>
      </li><!-- end of app resources -->
      <li class="toggle-list">
        <div><a href="../../../guide/topics/data/data-storage.html">
            <span class="en">Data Storage</span>
          </a></div>
          <ul>
            <li><a href="../../../guide/topics/data/backup.html">
                <span class="en">Data Backup</span>
              </a>
            </li>
          </ul>
      </li>
      <li><a href="../../../guide/topics/security/security.html">
            <span class="en">Security and Permissions</span>
          </a></li>
      <li class="toggle-list">
        <div><a href="../../../guide/topics/manifest/manifest-intro.html">
          <span class="en">The AndroidManifest.xml File</span>
        </a></div>
        <ul>
          <li><a href="../../../guide/topics/manifest/action-element.html">&lt;action&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/activity-alias-element.html">&lt;activity-alias&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/application-element.html">&lt;application&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/category-element.html">&lt;category&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/compatible-screens-element.html">&lt;compatible-screens&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/data-element.html">&lt;data&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/grant-uri-permission-element.html">&lt;grant-uri-permission&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/instrumentation-element.html">&lt;instrumentation&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/meta-data-element.html">&lt;meta-data&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/path-permission-element.html">&lt;path-permission&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/permission-group-element.html">&lt;permission-group&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/permission-tree-element.html">&lt;permission-tree&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/provider-element.html">&lt;provider&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/receiver-element.html">&lt;receiver&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/service-element.html">&lt;service&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/supports-gl-texture-element.html">&lt;supports-gl-texture&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/supports-screens-element.html">&lt;supports-screens&gt;</a></li><!-- ##api level 4## -->
          <li><a href="../../../guide/topics/manifest/uses-configuration-element.html">&lt;uses-configuration&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/uses-feature-element.html">&lt;uses-feature&gt;</a></li> <!-- ##api level 4## -->
          <li><a href="../../../guide/topics/manifest/uses-library-element.html">&lt;uses-library&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></li>
          <li><a href="../../../guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</a></li>
        </ul>
      </li><!-- end of the manifest file -->
    </ul>

    <ul>
    <li class="toggle-list">
        <div><a href="../../../guide/topics/graphics/index.html">
            <span class="en">Graphics</span>
          </a><span class="new-child">new!</span></div>
        <ul>
          <li><a href="../../../guide/topics/graphics/2d-graphics.html">
              <span class="en">Canvas and Drawables</span></a></li>
          <li><a href="../../../guide/topics/graphics/hardware-accel.html">
              <span class="en">Hardware Acceleration</span></a>
            <span class="new">new!</span></li>
          <li><a href="../../../guide/topics/graphics/opengl.html">
              <span class="en">OpenGL</span>
            </a><span class="new">updated</span></li>
        </ul>
      </li>
      <li class="toggle-list">
        <div><a href="../../../guide/topics/graphics/animation.html">
            <span class="en">Animation</span>
          </a></div>
        <ul>
          <li><a href="../../../guide/topics/graphics/prop-animation.html">
              <span class="en">Property Animation</span></a></li>
          <li><a href="../../../guide/topics/graphics/view-animation.html">
              <span class="en">View Animation</span></a></li>
          <li><a href="../../../guide/topics/graphics/drawable-animation.html">
              <span class="en">Drawable Animation</span></a></li>
        </ul>
      </li>
      <li class="toggle-list">
	        <div><a href="../../../guide/topics/renderscript/index.html">
	            <span class="en">RenderScript</span>
	          </a></div>
	        <ul>
	          <li><a href="../../../guide/topics/renderscript/graphics.html">
	                <span class="en">Graphics</span>
	              </a>
	          </li>
	          <li><a href="../../../guide/topics/renderscript/compute.html">
	                <span class="en">Compute</span>
	              </a>
	          </li>
	        </ul>
  	  </li>

      <li class="toggle-list">
          <div><a href="../../../guide/topics/media/index.html">
            <span class="en">Multimedia and Camera</span>
          </a><span class="new">updated</span></div>
          <ul>
            <li><a href="../../../guide/topics/media/mediaplayer.html">
                  <span class="en">Media Playback</span></a>
                </li>
            <li><a href="../../../guide/topics/media/jetplayer.html">
                  <span class="en">JetPlayer</span></a>
                </li>
            <li><a href="../../../guide/topics/media/camera.html">
                  <span class="en">Camera</span></a>
                  <span class="new">new!</span>
                </li>
            <li><a href="../../../guide/topics/media/audio-capture.html">
                  <span class="en">Audio Capture</span></a>
                </li>
          </ul>
      </li>
      <li>
        <a href="../../../guide/topics/clipboard/copy-paste.html">
            <span class="en">Copy and Paste</span>
        </a></li>
  <!--<li class="toggle-list">
        <div><a style="color:gray;">Sensors</a></div>
          <ul>
            <li><a style="color:gray;">Camera</a></li>
            <li><a style="color:gray;">Compass</a></li>
            <li><a style="color:gray;">Accelerometer</a></li>
          </ul>
      </li> -->
      <li class="toggle-list">
        <div><a href="../../../guide/topics/location/index.html">
               <span class="en">Location and Maps</span>
             </a></div>
        <ul>
          <li><a href="../../../guide/topics/location/obtaining-user-location.html">
                <span class="en">Obtaining User Location</span>
              </a></li>
        </ul>
      </li>
  <!--<li class="toggle-list">
        <div><a style="color:gray;">Wireless Controls</a></div>
          <ul>
            <li><a style="color:gray;">Wi-Fi</a></li>
          </ul>
      </li> -->
  <!--<li><a style="color:gray;">Localization</a></li>  -->
      <li><a href="../../../guide/topics/appwidgets/index.html">
            <span class="en">App Widgets</span></a>
          </li>
      <li><a href="../../../guide/topics/wireless/bluetooth.html">
            <span class="en">Bluetooth</span></a>
          </li>
      <li><a href="../../../guide/topics/nfc/index.html">
            <span class="en">Near Field Communication</span>
          </a></li>
      <li class="toggle-list">
          <div><a href="../../../guide/topics/usb/index.html">
            <span class="en">USB</span></a>
          </div>
            <ul>
              <li><a href="../../../guide/topics/usb/accessory.html">Accessory</a></li>
              <li><a href="../../../guide/topics/usb/host.html">Host</a></li>
              <li><a href="../../../guide/topics/usb/adk.html">Open Accessory Dev Kit</a></li>
            </ul>
          </li>

       <li><a href="../../../guide/topics/network/sip.html">
            <span class="en">Session Initiation Protocol</span>
          </a></li>
      <li class="toggle-list">
        <div><a href="../../../guide/topics/search/index.html">
            <span class="en">Search</span>
          </a></div>
          <ul>
            <li><a href="../../../guide/topics/search/search-dialog.html">Creating a Search Interface</a></li>
            <li><a href="../../../guide/topics/search/adding-recent-query-suggestions.html">Adding Recent Query Suggestions</a></li>
            <li><a href="../../../guide/topics/search/adding-custom-suggestions.html">Adding Custom Suggestions</a></li>
            <li><a href="../../../guide/topics/search/searchable-config.html">Searchable Configuration</a></li>
          </ul>
      </li>
      <li><a href="../../../guide/topics/admin/device-admin.html">
            <span class="en">Device Administration</span></a>
      </li>
      <li class="toggle-list">
           <div>
                <a href="../../../guide/topics/testing/index.html">
                   <span class="en">Testing</span>
               </a>
           </div>
           <ul>
              <li>
                <a href="../../../guide/topics/testing/testing_android.html">
                <span class="en">Testing Fundamentals</span></a>
              </li>
              <li>
                <a href="../../../guide/topics/testing/activity_testing.html">
                <span class="en">Activity Testing</span></a>
              </li>
              <li>
                <a href="../../../guide/topics/testing/contentprovider_testing.html">
                <span class="en">Content Provider Testing</span></a>
              </li>
              <li>
                <a href="../../../guide/topics/testing/service_testing.html">
                <span class="en">Service Testing</span></a>
              </li>
              <li>
                <a href="../../../guide/topics/testing/what_to_test.html">
                <span class="en">What To Test</span></a>
              </li>
           </ul>
      </li>
    </ul>
  </li>

  <li>
    <h2>
      <span class="en">Android Market Topics</span>
    </h2>
    <ul>
      <li><a href="../../../guide/publishing/licensing.html">
          <span class="en">Application Licensing</span></a>
      </li>
      <li class="toggle-list">
        <div><a href="../../../guide/market/billing/index.html">
            <span class="en">In-app Billing</span></a>
        </div>
        <ul>
          <li><a href="../../../guide/market/billing/billing_overview.html">
              <span class="en">In-app Billing Overview</span></a>
          </li>
          <li><a href="../../../guide/market/billing/billing_integrate.html">
              <span class="en">Implementing In-app Billing</span></a>
          </li>
          <li><a href="../../../guide/market/billing/billing_best_practices.html">
              <span class="en">Security and Design</span></a>
          </li>
          <li><a href="../../../guide/market/billing/billing_testing.html">
              <span class="en">Testing In-app Billing</span></a>
          </li>
          <li><a href="../../../guide/market/billing/billing_admin.html">
              <span class="en">Administering In-app Billing</span></a>
          </li>
          <li><a href="../../../guide/market/billing/billing_reference.html">
              <span class="en">In-app Billing Reference</span></a>
          </li>
        </ul>
      </li>
      <li><a href="../../../guide/appendix/market-filters.html">
          <span class="en">Market Filters</span></a>
      </li>
      <li><a href="../../../guide/market/publishing/multiple-apks.html">
          <span class="en">Multiple APK Support</span></a>
      </li>
    </ul>
  </li>


  <li>
    <h2><span class="en">Developing</span>
               <span class="de" style="display:none">Entwicklung</span>
               <span class="es" style="display:none">Desarrollo</span>
               <span class="fr" style="display:none">Développement</span>
               <span class="it" style="display:none">Sviluppo</span>
               <span class="ja" style="display:none">開発</span>
               <span class="zh-CN" style="display:none">开发</span>
               <span class="zh-TW" style="display:none">開發</span>
    </h2>
    <ul>
  <!--<li><a href="">Developing for Android</a></li>
      signing, upgrading, selecting a package name, select device profile, touch, trackball, dpad available, etc. -->
      <li>
        <a href="../../../guide/developing/index.html">
        <span class="en">Introduction</span></a>
      </li>

      <li class="toggle-list">
        <div>
           <a href="../../../guide/developing/devices/index.html">
                <span class="en">Managing Virtual Devices</span>
            </a>
        </div>
        <ul>
          <li>
            <a href="../../../guide/developing/devices/managing-avds.html">
              <span class="en">With AVD Manager</span>
            </a>
          </li>
          <li>
            <a href="../../../guide/developing/devices/managing-avds-cmdline.html">
              <span class="en">From the Command Line</span>
            </a>
          </li>
          <li>
           <a href="../../../guide/developing/devices/emulator.html">
                <span class="en">Using the Android Emulator</span>
            </a>
          </li>
        </ul>
      </li>
      <li>
        <a href="../../../guide/developing/device.html">
          <span class="en">Using Hardware Devices</span>
        </a>
      </li>

      <li class="toggle-list">
        <div>
          <a href="../../../guide/developing/projects/index.html">
            <span class="en">Managing Projects</span>
          </a>
        </div>
        <ul>
          <li>
            <a href="../../../guide/developing/projects/projects-eclipse.html">
              <span class="en">From Eclipse with ADT</span>
            </a>
          </li>
          <li>
            <a href="../../../guide/developing/projects/projects-cmdline.html">
                <span class="en">From the Command Line</span>
            </a>
          </li>
        </ul>
      </li>

      <li class="toggle-list">
        <div>
          <a href="../../../guide/developing/building/index.html">
            <span class="en">Building and Running</span>
          </a>
        </div>
        <ul>
          <li><a href="../../../guide/developing/building/building-eclipse.html">
            <span class="en">From Eclipse with ADT</span>
          </a></li>
          <li><a href="../../../guide/developing/building/building-cmdline.html">
            <span class="en">From the Command Line</span></a></li>
        </ul>
      </li>

      <li class="toggle-list">
        <div>
          <a href="../../../guide/developing/debugging/index.html">
            <span class="en">Debugging</span>
          </a>
        </div>
        <ul>
          <li>
            <a href="../../../guide/developing/debugging/debugging-projects.html">
                <span class="en">From Eclipse with ADT</span>
            </a>
          </li>
          <li>
            <a href="../../../guide/developing/debugging/debugging-projects-cmdline.html">
                <span class="en">From Other IDEs</span>
            </a>
          </li>
          <li>
            <a href="../../../guide/developing/debugging/ddms.html">
              <span class="en">Using DDMS</span>
            </a>
          </li>
          <li>
            <a href="../../../guide/developing/debugging/debugging-log.html">
                <span class="en">Reading and Writing Logs</span>
            </a>
          </li>
          <li>
            <a href="../../../guide/developing/debugging/debugging-ui.html">
                <span class="en">Debugging and Profiling UIs</span>
            </a>
          </li>
          <li>
            <a href="../../../guide/developing/debugging/debugging-tracing.html">
                <span class="en">Profiling with Traceview and dmtracedump</span>
            </a>
          </li>
          <li>
            <a href="../../../guide/developing/debugging/debugging-devtools.html">
                <span class="en">Using the Dev Tools App</span>
            </a>
          </li>
        </ul>
      </li>

      <li class="toggle-list">
           <div>
                <a href="../../../guide/developing/testing/index.html">
                   <span class="en">Testing</span>
               </a>
           </div>
           <ul>
              <li>
                <a href="../../../guide/developing/testing/testing_eclipse.html">
                  <span class="en">From Eclipse with ADT</span>
                </a>
              </li>

              <li>
                <a href="../../../guide/developing/testing/testing_otheride.html">
                  <span class="en">From Other IDEs</span>
                </a>
              </li>
           </ul>
         </li>

         <li class="toggle-list">
        <div><a href="../../../guide/developing/tools/index.html">
            <span class="en">Tools</span>
          </a></div>
        <ul>
          <li><a href="../../../guide/developing/tools/adb.html">adb</a></li>
          <li><a href="../../../guide/developing/tools/adt.html">ADT</a></li>
          <li><a href="../../../guide/developing/tools/android.html">android</a></li>
          <li><a href="../../../guide/developing/tools/bmgr.html">bmgr</a>
          <li><a href="../../../guide/developing/tools/dmtracedump.html">dmtracedump</a></li>
          <li><a href="../../../guide/developing/tools/draw9patch.html">Draw
          9-Patch</a></li>
          <li><a href="../../../guide/developing/tools/emulator.html">Emulator</a></li>
          <li><a href="../../../guide/developing/tools/etc1tool.html">etc1tool</a></li>
          <li><a href="../../../guide/developing/tools/hierarchy-viewer.html">Hierarchy Viewer</a></li>
          <li><a href="../../../guide/developing/tools/hprof-conv.html">hprof-conv</a></li>
          <li><a href="../../../guide/developing/tools/layoutopt.html">layoutopt</a></li>
          <li><a href="../../../guide/developing/tools/logcat.html">logcat</a></li>
          <li><a href="../../../guide/developing/tools/mksdcard.html">mksdcard</a></li>
          <li><a href="../../../guide/developing/tools/monkey.html">Monkey</a></li>
          <li class="toggle-list">
            <div><a href="../../../guide/developing/tools/monkeyrunner_concepts.html">
              <span class="en">monkeyrunner</span>
            </a></div>
            <ul>
              <li><a href="../../../guide/developing/tools/MonkeyDevice.html">
                <span class="en">MonkeyDevice</span>
                </a></li>
              <li><a href="../../../guide/developing/tools/MonkeyImage.html">
                <span class="en">MonkeyImage</span>
                </a></li>
              <li><a href="../../../guide/developing/tools/MonkeyRunner.html">
                <span class="en">MonkeyRunner</span>
                </a></li>
            </ul>
          </li>
          <li><a href="../../../guide/developing/tools/proguard.html">ProGuard</a></li>
          <li><a href="../../../guide/developing/tools/adb.html#sqlite">sqlite3</a></li>
          <li><a href="../../../guide/developing/tools/traceview.html">Traceview</a></li>
          <li><a href="../../../guide/developing/tools/zipalign.html">zipalign</a></li>
        </ul>
      </li>
    </ul>
  </li>

  <li>
    <h2><span class="en">Publishing</span>
        <span class="de" style="display:none">Veröffentlichung</span>
        <span class="es" style="display:none">Publicación</span>
        <span class="fr" style="display:none">Publication</span>
        <span class="it" style="display:none">Pubblicazione</span>
        <span class="ja" style="display:none">公開</span>
        <span class="zh-CN" style="display:none">发布</span>
        <span class="zh-TW" style="display:none">發佈</span>
    </h2>
    <ul>
      <li><a href="../../../guide/publishing/app-signing.html">
            <span class="en">Signing Your Applications</span>
            <span class="de" style="display:none">Signieren Ihrer Anwendungen</span>
            <span class="es" style="display:none">Firma de aplicaciones</span>
            <span class="fr" style="display:none">Attribution de votre signature <br />à vos applications</span>
            <span class="it" style="display:none">Firma delle applicazioni</span>
            <span class="ja" style="display:none">アプリケーションへの署名</span>
            <span class="zh-CN" style="display:none">应用程序签名</span>
            <span class="zh-TW" style="display:none">簽署應用程式</span>
          </a></li>
      <li><a href="../../../guide/publishing/versioning.html">
            <span class="en">Versioning Your Applications</span>
            <span class="de" style="display:none">Versionsverwaltung für Ihre <br />Anwendungen</span>
            <span class="es" style="display:none">Versiones de las aplicaciones</span>
            <span class="fr" style="display:none">Attribution d'une version à vos applications</span>
            <span class="it" style="display:none">Controllo versioni delle applicazioni</span>
            <span class="ja" style="display:none">アプリケーションのバージョニング</span>
            <span class="zh-CN" style="display:none">应用程序版本控制</span>
            <span class="zh-TW" style="display:none">應用程式版本設定</span>
          </a></li>
      <li><a href="../../../guide/publishing/preparing.html">
            <span class="en">Preparing to Publish</span>
            <span class="de" style="display:none">Vorbereitung auf die Veröffentlichung</span>
            <span class="es" style="display:none">Publicación de aplicaciones</span>
            <span class="fr" style="display:none">Préparation à la publication</span>
            <span class="it" style="display:none">Preparativi per la pubblicazione</span>
            <span class="ja" style="display:none">公開の準備</span>
            <span class="zh-CN" style="display:none">准备发布</span>
            <span class="zh-TW" style="display:none">準備發佈</span>
          </a></li>
      <li><a href="../../../guide/publishing/publishing.html">
            <span class="en">Publishing on Android Market</span>
          </a></li>
    </ul>
  </li>

  <li>
    <h2><span class="en">Best Practices</span>
               <span class="de" style="display:none">Bewährte Verfahren</span>
               <span class="es" style="display:none">Prácticas recomendadas</span>
               <span class="fr" style="display:none">Meilleures pratiques</span>
               <span class="it" style="display:none">Best practice</span>
               <span class="ja" style="display:none">ベスト プラクティス</span>
               <span class="zh-CN" style="display:none">最佳实践</span>
               <span class="zh-TW" style="display:none">最佳實務</span>
    </h2>
    <ul>
      <li><a href="../../../guide/practices/compatibility.html">
            <span class="en">Compatibility</span>
          </a></li>
      <li class="toggle-list">
        <div><a href="../../../guide/practices/screens_support.html">
          <span class="en">Supporting Multiple Screens</span>
        </a></div>
        <ul>
          <li><a href="../../../guide/practices/screens-distribution.html">
            <span class="en">Distributing to Specific Screens</span>
          </a></li>
          <li><a href="../../../guide/practices/screen-compat-mode.html">
            <span class="en">Screen Compatibility Mode</span>
          </a></li>
          <li><a href="../../../guide/practices/screens-support-1.5.html">
            <span class="en">Strategies for Android 1.5</span>
          </a></li>
        </ul>
      </li>
      <li><a href="../../../guide/practices/optimizing-for-3.0.html">
            <span class="en">Optimizing Apps for Android 3.0</span>
          </a></li>
      <li class="toggle-list">
        <div><a href="../../../guide/practices/ui_guidelines/index.html">
               <span class="en">UI Guidelines</span>
             </a></div>
        <ul>
          <li class="toggle-list">
            <div><a href="../../../guide/practices/ui_guidelines/icon_design.html">
                   <span class="en">Icon Design <span class="new">updated</span></span>
                 </a></div>
            <ul>
              <li><a href="../../../guide/practices/ui_guidelines/icon_design_launcher.html">
                    <span class="en">Launcher Icons <span class="new">updated</span></span>
                  </a></li>
              <li><a href="../../../guide/practices/ui_guidelines/icon_design_menu.html">
                    <span class="en">Menu Icons</span>
                  </a></li>
              <li><a href="../../../guide/practices/ui_guidelines/icon_design_action_bar.html">
                    <span class="en">Action Bar Icons <span class="new">new!</span></span>
                  </a></li>
              <li><a href="../../../guide/practices/ui_guidelines/icon_design_status_bar.html">
                    <span class="en">Status Bar Icons <span class="new">updated</span></span>
                  </a></li>
              <li><a href="../../../guide/practices/ui_guidelines/icon_design_tab.html">
                    <span class="en">Tab Icons</span>
                  </a></li>
              <li><a href="../../../guide/practices/ui_guidelines/icon_design_dialog.html">
                    <span class="en">Dialog Icons</span>
                  </a></li>
              <li><a href="../../../guide/practices/ui_guidelines/icon_design_list.html">
                    <span class="en">List View Icons</span>
                  </a></li>
            </ul>
          </li>
          <li><a href="../../../guide/practices/ui_guidelines/widget_design.html">
                <span class="en">App Widget Design <span class="new">updated</span></span>
              </a></li>
          <li><a href="../../../guide/practices/ui_guidelines/activity_task_design.html">
                <span class="en">Activity and Task Design</span>
              </a></li>
          <li><a href="../../../guide/practices/ui_guidelines/menu_design.html">
                <span class="en">Menu Design</span>
              </a></li>
        </ul>
      </li>
      </ul>
      <ul>
      <li><a href="../../../guide/practices/design/accessibility.html">
            <span class="en">Designing for Accessibility</span>
          </a></li>
      <li class="toggle-list">
        <div><a href="../../../guide/practices/design/performance.html">
            <span class="en">Designing for Performance</span>
          </a></div>
        <ul>
          <li><a href="../../../guide/practices/design/jni.html">
                <span class="en">JNI Tips</span>
              </a></li>
        </ul>
      </li>
      <li><a href="../../../guide/practices/design/responsiveness.html">
            <span class="en">Designing for Responsiveness</span>
          </a></li>
      <li><a href="../../../guide/practices/design/seamlessness.html">
            <span class="en">Designing for Seamlessness</span>
          </a></li>
    </ul>
  </li>

  <li>
    <h2><span class="en">Web Applications</span>
    </h2>
    <ul>
      <li><a href="../../../guide/webapps/index.html">
            <span class="en">Web Apps Overview</span>
          </a></li>
      <li><a href="../../../guide/webapps/targeting.html">
            <span class="en">Targeting Screens from Web Apps</span>
          </a></li>
      <li><a href="../../../guide/webapps/webview.html">
            <span class="en">Building Web Apps in WebView</span>
          </a></li>
      <li><a href="../../../guide/webapps/debugging.html">
            <span class="en">Debugging Web Apps</span>
          </a></li>
      <li><a href="../../../guide/webapps/best-practices.html">
            <span class="en">Best Practices for Web Apps</span>
          </a></li>
    </ul>
  </li>

  <li>
    <h2><span class="en">Appendix</span>
               <span class="de" style="display:none">Anhang</span>
               <span class="es" style="display:none">Apéndice</span>
               <span class="fr" style="display:none">Annexes</span>
               <span class="it" style="display:none">Appendice</span>
               <span class="ja" style="display:none">付録</span>
               <span class="zh-CN" style="display:none">附录</span>
               <span class="zh-TW" style="display:none">附錄</span>
    </h2>
    <ul>
      <li><a href="../../../guide/appendix/api-levels.html">
            <span class="en">Android API Levels</span>
          </a></li>
      <li><a href="../../../guide/appendix/install-location.html">
            <span class="en">App Install Location</span>
          </a></li>
      <li><a href="../../../guide/appendix/media-formats.html">
            <span class="en">Supported Media Formats <span class="new">updated</span></span>
          </a></li>
      <li><a href="../../../guide/appendix/g-app-intents.html">
            <span class="en">Intents List: Google Apps</span>
          </a></li>
      <li><a href="../../../guide/developing/tools/aidl.html">AIDL</a></li>
      <li><a href="../../../guide/appendix/glossary.html">
            <span class="en">Glossary</span>
          </a></li>
    </ul>
  </li>

</ul>

<script type="text/javascript">
<!--
    buildToggleLists();
    changeNavLang(getLangPref());
//-->
</script>

      </div>
    </div> <!-- end side-nav -->
    <script>
      addLoadEvent(function() {
        scrollIntoView("devdoc-nav");
        });
    </script>




<div class="g-unit" id="doc-content"><a name="top"></a>

<div id="jd-header" class="guide-header">
  <span class="crumb">
    
      <a href="index.html">Search</a> >
    
  </span>
<h1>Creating a Search Interface</h1>
</div>

  <div id="jd-content">

    <div class="jd-descr">
    <div id="qv-wrapper">
<div id="qv">

  <h2>Quickview</h2>
  <ul>
    <li>The Android system sends search queries from the search dialog or widget to an activity you
specify to perform searches and present results</li>
    <li>You can put the search widget in the Action Bar, as an "action view," for quick
access</li>
  </ul>


<h2>In this document</h2>
<ol>
  <li><a href="#TheBasics">The Basics</a></li>
  <li><a href="#SearchableConfiguration">Creating a Searchable Configuration</a></li>
  <li><a href="#SearchableActivity">Creating a Searchable Activity</a>
    <ol>
      <li><a href="#DeclaringSearchableActivity">Declaring a searchable activity</a></li>
      <li><a href="#PerformingSearch">Performing a search</a></li>
    </ol>
  </li>
  <li><a href="#SearchDialog">Using the Search Dialog</a>
    <ol>
      <li><a href="#InvokingTheSearchDialog">Invoking the search dialog</a></li>
      <li><a href="#LifeCycle">The impact of the search dialog on your activity lifecycle</a></li>
      <li><a href="#SearchContextData">Passing search context data</a></li>
    </ol>
  </li>
  <li><a href="#UsingSearchWidget">Using the Search Widget</a>
    <ol>
      <li><a href="#ConfiguringWidget">Configuring the search widget</a></li>
      <li><a href="#WidgetFeatures">Other search widget features</a></li>
      <li><a href="#UsingBoth">Using both the widget and the dialog</a></li>
    </ol>
  </li>
  <li><a href="#VoiceSearch">Adding Voice Search</a></li>
  <li><a href="#SearchSuggestions">Adding Search Suggestions</a></li>
</ol>

<h2>Key classes</h2>
<ol>
<li><code><a href="../../../reference/android/app/SearchManager.html">SearchManager</a></code></li>
<li><code><a href="../../../reference/android/widget/SearchView.html">SearchView</a></code></li>
</ol>

<h2>Related samples</h2>
<ol>
<li><a href="../../../resources/samples/SearchableDictionary/index.html">Searchable
Dictionary</a></li>
<li><a href="../../../resources/samples/ApiDemos/src/com/example/android/apis/view/SearchViewActionBar.html">SearchView
    in the Action Bar</a></li>
<li><a href="../../../resources/samples/ApiDemos/src/com/example/android/apis/view/SearchViewFilterMode.html">SearchView
    filter mode</a></li>
</ol>

<h2>Downloads</h2>
<ol>
<li><a href="../../../shareables/search_icons.zip">search_icons.zip</a></li>
</ol>

<h2>See also</h2>
<ol>
<li><a href="adding-recent-query-suggestions.html">Adding Recent Query Suggestions</a></li>
<li><a href="adding-custom-suggestions.html">Adding Custom Suggestions</a></li>
<li><a href="searchable-config.html">Searchable Configuration</a></li>
</ol>

</div>
</div>

<p>When you're ready to add search functionality to your application, Android helps you implement
the user interface with either a search dialog that appears at the top of the activity window or a
search widget that you can insert in your layout. Both the search dialog and the widget can deliver
the user's search query to a specific activity in your application. This way, the user can initiate
a search from any activity where the search dialog or widget is available, and the system starts the
appropriate activity to perform the search and present results.</p>

<p>Other features available for the search dialog and widget include:</p>

<ul>
  <li>Voice search</li>
  <li>Search suggestions based on recent queries</li>
  <li>Search suggestions that match actual results in your application data</li>
</ul>

<p>This guide shows you how to set up your application to provide a search interface
that's assisted by the Android system to deliver search queries, using either the
search dialog or the search widget.</p>


<h2 id="TheBasics">The Basics</h2>

<div class="figure" style="width:250px">
<img src="../../../images/search/search-ui.png" alt="" height="417" />
<p class="img-caption"><strong>Figure 1.</strong> Screenshot of an application's search dialog.</p>
</div>

<p>Before you begin, you should decide whether you'll implement your search interface using the
search dialog or the search widget. Both provide the same search features, but in slightly different
ways:</p>

<ul>
  <li>The <strong>search dialog</strong> is a UI component that's controlled by the Android system.
When activated by the user, the search dialog appears at the top of the activity, as shown in figure
1.
    <p>The Android system controls all events in the search dialog. When the user
submits a query, the system delivers the query to the activity that you specify to
handle searches. The dialog can also provide search suggestions while the user types.</p></li>

  <li>The <strong>search widget</strong> is an instance of <code><a href="../../../reference/android/widget/SearchView.html">SearchView</a></code> that
you can place anywhere in your layout. By default, the search widget behaves like a standard <code><a href="../../../reference/android/widget/EditText.html">EditText</a></code> widget and doesn't do anything, but you can configure it so that the
Android system handles all input events, delivers queries to the appropriate activity, and provides
search suggestions (just like the search dialog). However, the search widget is available only in
Android 3.0 (API Level 11) and higher.

<p class="note"><strong>Note:</strong> If you want, you can handle all user input into the
search widget yourself, using various callback methods and listeners. This document, however,
focuses on how to integrate the search widget with the system for an assisted search
implementation. If you want to handle all user input yourself, read the reference documentation for
<code><a href="../../../reference/android/widget/SearchView.html">SearchView</a></code> and its nested interfaces. </p></li>
</ul>

<p>When the user executes a search from the search dialog or a search widget, the system creates an
<code><a href="../../../reference/android/content/Intent.html">Intent</a></code> and stores the user query in it. The system then starts the activity
that you've declared to handle searches (the "searchable activity") and delivers it the intent. To
set up your application for this kind of assisted search, you need the following:</p>

<ul>
  <li>A searchable configuration
  <p>An XML file that configures some settings for the search dialog or widget. It includes settings
for features such as voice search, search suggestion, and hint text for the search box.</p></li>
  <li>A searchable activity
  <p>The <code><a href="../../../reference/android/app/Activity.html">Activity</a></code> that receives the search query, searches your
data, and displays the search results.</p></li>
  <li>A search interface, provided by either:
    <ul>
      <li>The search dialog
        <p>By default, the search dialog is hidden, but appears at the top of the screen when the 
user presses the device SEARCH button (when available) or another button in your user interface.</p>
      </li>
      <li>Or, a <code><a href="../../../reference/android/widget/SearchView.html">SearchView</a></code> widget
        <p>Using the search widget allows you to put the search box anywhere in your activity.
Instead of putting it in your activity layout, however, it's usually more convenient for users as an
<a href="../../../guide/topics/ui/actionbar.html#ActionView">action view in the Action Bar</a>.</p>
      </li>
    </ul>
  </li>
</ul>

<p>The rest of this document shows you how to create the searchable configuration, searchable
activity, and implement a search interface with either the search dialog or search widget.</p>


<h2 id="SearchableConfiguration">Creating a Searchable Configuration</h2>

<p>The first thing you need is an XML file called the searchable configuration. It configures
certain UI aspects of the search dialog or widget and defines how features such as suggestions and
voice search behave. This file is traditionally named <code>searchable.xml</code> and must be saved in
the <code>res/xml/</code> project directory.</p>

<p class="note"><strong>Note:</strong> The system uses this file to instantiate a <code><a href="../../../reference/android/app/SearchableInfo.html">SearchableInfo</a></code> object, but you cannot create this object yourself at
runtime&mdash;you must declare the searchable configuration in XML.</p>

<p>The searchable configuration file must include the <a
href="../../../guide/topics/search/searchable-config.html#searchable-element"><code>&lt;searchable&gt;</code></a> element as the root node and specify one
or more attributes. For example:</p>

<pre>
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint" >
&lt;/searchable>
</pre>

<p>The <code>android:label</code> attribute is the only required attribute. It points to a string
resource, which should be the application name. This label isn't actually visible to the
user until you enable search suggestions for Quick Search Box. At that point, this label is visible
in the list of Searchable items in the system Settings.</p>

<p>Though it's not required, we recommend that you always include the <code>android:hint</code>
attribute, which provides a hint string in the search box before users
enters a query. The hint is important because it provides important clues to users about what
they can search.</p>

<p class="note"><strong>Tip:</strong> For consistency among other
Android applications, you should format the string for <code>android:hint</code> as "Search
&lt;content-or-product&gt;". For example, "Search songs and artists" or "Search
YouTube".</p>

<p>The <a
href="../../../guide/topics/search/searchable-config.html#searchable-element"><code>&lt;searchable&gt;</code></a> element accepts several other attributes. However, you don't need
most attributes until you add features such as <a href="#SearchSuggestions">search suggestions</a>
and <a href="#VoiceSearch">voice search</a>. For detailed information about the searchable
configuration file, see the <a
href="../../../guide/topics/search/searchable-config.html">Searchable Configuration</a> reference
document.</p>



<h2 id="SearchableActivity">Creating a Searchable Activity</h2>

<p>A searchable activity is the <code><a href="../../../reference/android/app/Activity.html">Activity</a></code> in your application that performs
searches based on a query string and presents the search results.</p>

<p>When the user executes a search in the search dialog or widget, the system starts your
searchable activity and delivers it the search query in an <code><a href="../../../reference/android/content/Intent.html">Intent</a></code> with the  <code><a href="../../../reference/android/content/Intent.html#ACTION_SEARCH">ACTION_SEARCH</a></code> action. Your
searchable activity retrieves the query from the intent's <code><a href="../../../reference/android/app/SearchManager.html#QUERY">QUERY</a></code> extra, then searches your data and presents the results.</p>

<p>Because you may include the search dialog or widget in any other activity in your application,
the system must know which activity is your searchable activity, so it can properly deliver the
search query. So, you must first declare your searchable activity in the Android manifest file.</p>


<h3 id="DeclaringSearchableActivity">Declaring a searchable activity</h3>

<p>If you don't have one already, create an <code><a href="../../../reference/android/app/Activity.html">Activity</a></code> that will perform
searches and present results. You don't need to implement the search functionality yet&mdash;just
create an activity that you can declare in the manifest. Inside the manifest's <a
href="../../../guide/topics/manifest/activity-element.html"><code>&lt;activity&gt;</code></a>
element:</p>
<ol>
  <li>Declare the activity to accept the <code><a href="../../../reference/android/content/Intent.html#ACTION_SEARCH">ACTION_SEARCH</a></code> intent, in an
<a href="../../../guide/topics/manifest/intent-filter-element.html"><code>&lt;intent-filter&gt;</code></a>
element.</li>
  <li>Specify the searchable configuration to use, in a <a
href="../../../guide/topics/manifest/meta-data-element.html"><code>&lt;meta-data&gt;</code></a>
element.</li>
</ol>

<p>For example:</p>

<pre>
&lt;application ... >
    &lt;activity android:name=".SearchableActivity" >
        &lt;intent-filter>
            &lt;action android:name="android.intent.action.SEARCH" />
        &lt;/intent-filter>
        &lt;meta-data android:name="android.app.searchable"
                   android:resource="@xml/searchable"/>
    &lt;/activity>
    ...
&lt;/application>
</pre>

<p>The <code>&lt;meta-data&gt;</code> element must include the <code>android:name</code> attribute with a
value of <code>"android.app.searchable"</code> and the <code>android:resource</code> attribute with a
reference to the searchable configuration file (in this example, it
refers to the <code>res/xml/searchable.xml</code> file).</p>

<p class="note"><strong>Note:</strong> The <a
href="../../../guide/topics/manifest/intent-filter-element.html"><code>&lt;intent-filter&gt;</code></a> does not need a <a
href="../../../guide/topics/manifest/category-element.html"><code>&lt;category&gt;</code></a> with the
<code>DEFAULT</code> value (which you usually see in <a
href="../../../guide/topics/manifest/activity-element.html"><code>&lt;activity&gt;</code></a> elements),
because the system delivers the <code><a href="../../../reference/android/content/Intent.html#ACTION_SEARCH">ACTION_SEARCH</a></code> intent explicitly to
your searchable activity, using its component name.</p>



<h3 id="PerformingSearch">Performing a search</h3>

<p>Once you have declared your searchable activity in the manifest, performing a search in your
searchable activity involves three steps:</p>

<ol>
  <li><a href="#ReceivingTheQuery">Receiving the query</a></li>
  <li><a href="#SearchingYourData">Searching your data</a></li>
  <li><a href="#PresentingTheResults">Presenting the results</a></li>
</ol>

<p>Traditionally, your search results should be presented in a <code><a href="../../../reference/android/widget/ListView.html">ListView</a></code>, so
you might want your searchable activity to extend <code><a href="../../../reference/android/app/ListActivity.html">ListActivity</a></code>. It includes
a default layout with a single <code><a href="../../../reference/android/widget/ListView.html">ListView</a></code> and provides several
convenience methods for working with the <code><a href="../../../reference/android/widget/ListView.html">ListView</a></code>.</p>


<h4 id="ReceivingTheQuery">Receiving the query</h4>

<p>When a user executes a search from the search dialog or widget, the system starts your
searchable activity and sends it a <code><a href="../../../reference/android/content/Intent.html#ACTION_SEARCH">ACTION_SEARCH</a></code> intent. This intent
carries the search query in the
<code><a href="../../../reference/android/app/SearchManager.html#QUERY">QUERY</a></code> string extra. You must check for
this intent when the activity starts and extract the string. For example, here's how you can get the
search query when your searchable activity starts:</p>

<pre>
&#64;Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.search);

    // Get the intent, verify the action and get the query
    Intent intent = getIntent();
    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
      String query = intent.getStringExtra(SearchManager.QUERY);
      doMySearch(query);
    }
}
</pre>

<p>The <code><a href="../../../reference/android/app/SearchManager.html#QUERY">QUERY</a></code> string is always included with
the <code><a href="../../../reference/android/content/Intent.html#ACTION_SEARCH">ACTION_SEARCH</a></code> intent. In this example, the query is
retrieved and passed to a local <code>doMySearch()</code> method where the actual search operation
is done.</p>


<h4 id="SearchingYourData">Searching your data</h4>

<p>The process of storing and searching your data is unique to your application.
You can store and search your data in many ways, but this guide does not show you how to store your
data and search it. Storing and searching your data is something you should carefully consider in
terms of your needs and your data format. However, here are some tips you might be able to
apply:</p>

  <ul>
    <li>If your data is stored in a SQLite database on the device, performing a full-text search
(using FTS3, rather than a <code>LIKE</code> query) can provide a more robust search across text data and
can produce results significantly faster. See <a href="http://sqlite.org/fts3.html">sqlite.org</a>
for information about FTS3 and the <code><a href="../../../reference/android/database/sqlite/SQLiteDatabase.html">SQLiteDatabase</a></code> class for
information about SQLite on Android. Also look at the <a
href="../../../resources/samples/SearchableDictionary/index.html">Searchable Dictionary</a> sample
application to see a complete SQLite implementation that performs searches with FTS3.</li>
    <li>If your data is stored online, then the perceived search performance might be
inhibited by the user's data connection. You might want to display a spinning progress wheel until
your search returns. See <code><a href="../../../reference/android/net/package-summary.html">android.net</a></code> for a reference of network APIs and <a
href="../../../guide/topics/ui/dialogs.html#ProgressDialog">Creating a Progress Dialog</a>
for information about how to display a progress wheel.</li>
  </ul>


<div class="sidebox-wrapper">
<div class="sidebox">
<h2>About Adapters</h2>
<p>An <code><a href="../../../reference/android/widget/Adapter.html">Adapter</a></code> binds each item from a set of data into a
<code><a href="../../../reference/android/view/View.html">View</a></code> object. When the <code><a href="../../../reference/android/widget/Adapter.html">Adapter</a></code>
is applied to a <code><a href="../../../reference/android/widget/ListView.html">ListView</a></code>, each piece of data is inserted as an individual
view into the list. <code><a href="../../../reference/android/widget/Adapter.html">Adapter</a></code> is just an interface, so implementations such as <code><a href="../../../reference/android/widget/CursorAdapter.html">CursorAdapter</a></code> (for binding data from a <code><a href="../../../reference/android/database/Cursor.html">Cursor</a></code>) are needed.
If none of the existing implementations work for your data, then you can implement your own from
<code><a href="../../../reference/android/widget/BaseAdapter.html">BaseAdapter</a></code>. Install the SDK Samples package for API Level 4 to see the
original version of the Searchable Dictionary, which creates a custom adapter to read data from
a file.</p>
</div>
</div>

<p>Regardless of where your data lives and how you search it, we recommend that you return search
results to your searchable activity with an <code><a href="../../../reference/android/widget/Adapter.html">Adapter</a></code>. This way, you can easily
present all the search results in a <code><a href="../../../reference/android/widget/ListView.html">ListView</a></code>. If your data comes from a
SQLite database query, you can apply your results to a <code><a href="../../../reference/android/widget/ListView.html">ListView</a></code>
using a <code><a href="../../../reference/android/widget/CursorAdapter.html">CursorAdapter</a></code>. If your data comes in some other type of format, then
you can create an extension of <code><a href="../../../reference/android/widget/BaseAdapter.html">BaseAdapter</a></code>.</p>


<h4 id="PresentingTheResults">Presenting the results</h4>

<p>As discussed above, the recommended UI for your search results is a <code><a href="../../../reference/android/widget/ListView.html">ListView</a></code>, so you might want your searchable activity to extend <code><a href="../../../reference/android/app/ListActivity.html">ListActivity</a></code>. You can then call <code><a href="../../../reference/android/app/ListActivity.html#setListAdapter(android.widget.ListAdapter)">setListAdapter()</a></code>, passing it an <code><a href="../../../reference/android/widget/Adapter.html">Adapter</a></code> that is bound to your data. This injects all the
search results into the activity <code><a href="../../../reference/android/widget/ListView.html">ListView</a></code>.</p>

<p>For more help presenting your results in a list, see the <code><a href="../../../reference/android/app/ListActivity.html">ListActivity</a></code>
documentation.</p>

<p>Also see the <a
href="../../../resources/samples/SearchableDictionary/index.html">Searchable Dictionary</a> sample
for an a complete demonstration of how to search an SQLite database and use an
<code><a href="../../../reference/android/widget/Adapter.html">Adapter</a></code> to provide results in a <code><a href="../../../reference/android/widget/ListView.html">ListView</a></code>.</p>





<h2 id="SearchDialog">Using the Search Dialog</h2>

<div class="sidebox-wrapper">
<div class="sidebox">
  <h2>Should I use the search dialog or the widget?</h2>
  <p>The answer depends mostly on whether you are developing for Android 3.0 (API Level 11 or
higher), because the <code><a href="../../../reference/android/widget/SearchView.html">SearchView</a></code> widget was introduced in Android 3.0. So,
if you are developing your application for a version of Android lower than 3.0, the search widget is
not an option and you should use the search dialog to implement your search interface.</p>
  <p>If you <em>are</em> developing for Android 3.0 or higher, then the decision depends more on
your needs. In most cases, we recommend that you use the search widget as an "action view" in the
Action Bar. However, it might not be an option for you to put the search
widget in the Action Bar for some reason (perhaps there's not enough space or you don't use the
Action Bar). So, you might instead want to put the search widget somewhere in your activity layout.
And if all else fails, you can still use the search dialog if you prefer to keep the search box
hidden. In fact, you might want to offer both the dialog and the widget in some cases. For more
information about the widget, skip to <a href="#UsingSearchWidget">Using the Search Widget</a>.</p>
</div>
</div>

<p>The search dialog provides a floating search box at the top of the screen, with the application
icon on the left. The search dialog can provide search suggestions as the user types and, when
the user executes a search, the system sends the search query to a
searchable activity that performs the search. However, if you are developing
your application for devices running Android 3.0, you should consider using the search widget
instead (see the side box).</p>

<p>The search dialog is always hidden by default, until the user activates it. If the user's device
includes a SEARCH button, pressing it will activate the search dialog by default. Your application
can also activate the search dialog on demand by calling <code><a href="../../../reference/android/app/Activity.html#onSearchRequested()">onSearchRequested()</a></code>. However, neither of these work
until you enable the search dialog for the activity.</p>

<p>To enable the search dialog, you must indicate to the system which searchable activity should
receive search queries from the search dialog, in order to perform searches. For example, in the
previous section about <a href="#SearchableActivity">Creating a Searchable Activity</a>, a
searchable activity named <code>SearchableActivity</code> was created. If you want a separate activity,
named <code>OtherActivity</code>, to show the search dialog and deliver searches to <code>SearchableActivity</code>, you must declare in the manifest that <code>SearchableActivity</code> is the
searchable activity to use for the search dialog in <code>OtherActivity</code>.</p>

<p>To declare the searchable activity for an activity's search dialog,
add a <a href="../../../guide/topics/manifest/meta-data-element.html"><code>&lt;meta-data&gt;</code></a>
element inside the respective activity's <a
href="../../../guide/topics/manifest/activity-element.html"><code>&lt;activity&gt;</code></a> element.
The <a href="../../../guide/topics/manifest/meta-data-element.html"><code>&lt;meta-data&gt;</code></a>
element must include the <code>android:value</code> attribute that specifies the searchable activity's
class name and the <code>android:name</code> attribute with a value of <code>"android.app.default_searchable"</code>.</p>

<p>For example, here is the declaration for
both a searchable activity, <code>SearchableActivity</code>, and another activity, <code>OtherActivity</code>, which uses <code>SearchableActivity</code> to perform searches executed from its
search dialog:</p>

<pre>
&lt;application ... >
    &lt;!-- this is the searchable activity; it performs searches --&gt;
    &lt;activity android:name=".SearchableActivity" >
        &lt;intent-filter>
            &lt;action android:name="android.intent.action.SEARCH" />
        &lt;/intent-filter>
        &lt;meta-data android:name="android.app.searchable"
                   android:resource="@xml/searchable"/>
    &lt;/activity>

    &lt;!-- this activity enables the search dialog to initiate searches
         in the SearchableActivity --&gt;
    &lt;activity android:name=".OtherActivity" ... >
        &lt;!-- enable the search dialog to send searches to SearchableActivity -->
        <b>&lt;meta-data android:name="android.app.default_searchable"
                   android:value=".SearchableActivity" /&gt;</b>
    &lt;/activity>
    ...
&lt;/application>
</pre>

<p>Because the <code>OtherActivity</code> now includes a <a
href="../../../guide/topics/manifest/meta-data-element.html"><code>&lt;meta-data&gt;</code></a>
element to declare which searchable activity to use for searches, the activity has enabled the
search dialog.
While the user is in this activity, the device SEARCH button (if available) and the <code><a href="../../../reference/android/app/Activity.html#onSearchRequested()">onSearchRequested()</a></code> method will activate the search dialog.
When the user executes the search, the system starts <code>SearchableActivity</code> and delivers it
the <code><a href="../../../reference/android/content/Intent.html#ACTION_SEARCH">ACTION_SEARCH</a></code> intent.</p>

<p class="note"><strong>Note:</strong> The searchable activity itself provides the search dialog
by default, so you don't need to add this declaration to <code>SearchableActivity</code>.</p>

<p>If you want every activity in your application to provide the search dialog, insert the above <a
href="../../../guide/topics/manifest/meta-data-element.html"><code>&lt;meta-data&gt;</code></a>
element as a child of the <a
href="../../../guide/topics/manifest/application-element.html"><code>&lt;application&gt;</code></a>
element, instead of each <a
href="../../../guide/topics/manifest/activity-element.html"><code>&lt;activity&gt;</code></a>. This
way, every activity inherits the value, provides the search dialog, and delivers searches to
the same searchable activity. (If you have multiple searchable activities, you can override the
default searchable activity by placing a different <a
href="../../../guide/topics/manifest/meta-data-element.html"><code>&lt;meta-data&gt;</code></a>
declaration inside individual activities.)</p>

<p>With the search dialog now enabled for your activities, your application is ready to perform
searches.</p>


<h3 id="InvokingTheSearchDialog">Invoking the search dialog</h3>

<p>As mentioned above, the device SEARCH button will open the search dialog as long as the current
activity has declared in the manifest the searchable activity to use.</p>

<p>However, some devices do not include a dedicated SEARCH button, so you should not assume that
it's always available. When using the search dialog, you must <strong>always provide another search
button in your UI</strong> that activates the search dialog by calling <code><a href="../../../reference/android/app/Activity.html#onSearchRequested()">onSearchRequested()</a></code>.</p>

<p>For instance, you should either provide a menu item in your <a
href="../../../guide/topics/ui/menus.html#options-menu">Options Menu</a> or a button in your
activity layout that
activates search by calling <code><a href="../../../reference/android/app/Activity.html#onSearchRequested()">onSearchRequested()</a></code>. The <a
href="../../../shareables/search_icons.zip">search_icons.zip</a> file includes icons for
medium and high density screens, which you can use for your search menu item or button (low-density
screens scale-down the hdpi image by one half). </p>

<p>You can also enable "type-to-search" functionality, which activates the search dialog when the
user starts typing on the keyboard&mdash;the keystrokes are inserted into the search dialog. You can
enable type-to-search in your activity by calling
<code><a href="../../../reference/android/app/Activity.html#setDefaultKeyMode(int)">setDefaultKeyMode</a></code>(<code><a href="../../../reference/android/app/Activity.html#DEFAULT_KEYS_SEARCH_LOCAL">DEFAULT_KEYS_SEARCH_LOCAL</a></code>) during your activity's
<code><a href="../../../reference/android/app/Activity.html#onCreate(android.os.Bundle)">onCreate()</a></code> method.</p>


<h3 id="LifeCycle">The impact of the search dialog on your activity lifecycle</h3>

<p>The search dialog is a <code><a href="../../../reference/android/app/Dialog.html">Dialog</a></code> that floats at the top of the
screen. It does not cause any change in the activity stack, so when the search dialog appears, no
lifecycle methods (such as <code><a href="../../../reference/android/app/Activity.html#onPause()">onPause()</a></code>) are called. Your activity just
loses input focus, as input focus is given to the search dialog.
</p>

<p>If you want to be notified when the search dialog is activated, override the <code><a href="../../../reference/android/app/Activity.html#onSearchRequested()">onSearchRequested()</a></code> method. When the system calls this method, it is an
indication that your activity has lost input focus to the search dialog, so you can do any
work appropriate for the event (such as pause
a game). Unless you are <a
href="#SearchContextData">passing search context data</a>
(discussed below), you should end the method by calling the super class implementation. For
example:</p>

<pre>
&#64;Override
public boolean onSearchRequested() {
    pauseSomeStuff();
    return super.onSearchRequested();
}
</pre>

<p>If the user cancels search by pressing the BACK button, the search dialog closes and the activity
regains input focus. You can register to be notified when the search dialog is
closed with <code><a href="../../../reference/android/app/SearchManager.html#setOnDismissListener(android.app.SearchManager.OnDismissListener)">setOnDismissListener()</a></code>
and/or <code><a href="../../../reference/android/app/SearchManager.html#setOnCancelListener(android.app.SearchManager.OnCancelListener)">setOnCancelListener()</a></code>. You
should need to register only the <code><a href="../../../reference/android/app/SearchManager.OnDismissListener.html">OnDismissListener</a></code>, because it is called every time the search dialog closes. The <code><a href="../../../reference/android/app/SearchManager.OnCancelListener.html">OnCancelListener</a></code> only pertains to events in which the
user explicitly exited the search dialog, so it is not called when a search is executed (in which
case, the search dialog naturally disappears).</p>

<p>If the current activity is not the searchable activity, then the normal activity lifecycle
events are triggered once the user executes a search (the current activity receives <code><a href="../../../reference/android/app/Activity.html#onPause()">onPause()</a></code> and so forth, as
described in the <a
href="../../../guide/topics/fundamentals/activities.html#Lifecycle">Activities</a>
document). If, however, the current activity is the searchable activity, then one of two
things happens:</p>

<ol type="a">
  <li>By default, the searchable activity receives the <code><a href="../../../reference/android/content/Intent.html#ACTION_SEARCH">ACTION_SEARCH</a></code> intent with a call to <code><a href="../../../reference/android/app/Activity.html#onCreate(android.os.Bundle)">onCreate()</a></code> and a new instance of the
activity is brought to the top of the activity stack. There are now two instances of your
searchable activity in the activity stack (so pressing the BACK button goes back to the previous
instance of the searchable activity, rather than exiting the searchable activity).</li>
  <li>If you set <code>android:launchMode</code> to <code>"singleTop"</code>, then the
searchable activity receives the <code><a href="../../../reference/android/content/Intent.html#ACTION_SEARCH">ACTION_SEARCH</a></code> intent with a call
to <code><a href="../../../reference/android/app/Activity.html#onNewIntent(android.content.Intent)">onNewIntent(Intent)</a></code>, passing the new <code><a href="../../../reference/android/content/Intent.html#ACTION_SEARCH">ACTION_SEARCH</a></code> intent here. For example, here's how you might handle
this case, in which the searchable activity's launch mode is <code>"singleTop"</code>:
<pre>
&#64;Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.search);
    handleIntent(getIntent());
}

&#64;Override
protected void onNewIntent(Intent intent) {
    setIntent(intent);
    handleIntent(intent);
}

private void handleIntent(Intent intent) {
    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
      String query = intent.getStringExtra(SearchManager.QUERY);
      doMySearch(query);
    }
}
</pre>

<p>Compared to the example code in the section about <a href="#PerformingSearch">Performing a
Search</a>, all the code to handle the
search intent is now in the <code>handleIntent()</code> method, so that both <code><a href="../../../reference/android/app/Activity.html#onCreate(android.os.Bundle)">onCreate()</a></code> and <code><a href="../../../reference/android/app/Activity.html#onNewIntent(android.content.Intent)">onNewIntent()</a></code> can execute it.</p>

<p>When the system calls <code><a href="../../../reference/android/app/Activity.html#onNewIntent(android.content.Intent)">onNewIntent(Intent)</a></code>, the activity has
not been restarted, so the <code><a href="../../../reference/android/app/Activity.html#getIntent()">getIntent()</a></code> method
returns the same intent that was received with <code><a href="../../../reference/android/app/Activity.html#onCreate(android.os.Bundle)">onCreate()</a></code>. This is why you should call <code><a href="../../../reference/android/app/Activity.html#setIntent(android.content.Intent)">setIntent(Intent)</a></code> inside <code><a href="../../../reference/android/app/Activity.html#onNewIntent(android.content.Intent)">onNewIntent(Intent)</a></code> (so that the intent saved by the activity is updated in
case you call <code><a href="../../../reference/android/app/Activity.html#getIntent()">getIntent()</a></code> in the future).</p>

</li>
</ol>

<p>The second scenario using <code>"singleTop"</code> launch mode is usually ideal, because chances
are good that once a search is done, the user will perform additional searches and it's a bad
experience if your application creates multiple instances of the searchable activity. So, we
recommend that you set your searchable activity to <code>"singleTop"</code> launch mode in the
application manifest. For example:</p>

<pre>
&lt;activity android:name=".SearchableActivity"
          <b>android:launchMode="singleTop"</b> >
    &lt;intent-filter>
        &lt;action android:name="android.intent.action.SEARCH" />
    &lt;/intent-filter>
    &lt;meta-data android:name="android.app.searchable"
                      android:resource="@xml/searchable"/>
  &lt;/activity>
</pre>



<h3 id="SearchContextData">Passing search context data</h3>

<p>In some cases, you can make necessary refinements to the search query inside the searchable
activity, for every search made. However, if you want to refine your search criteria based on the
activity from which the user is performing a search, you can provide additional data in the intent
that the system sends to your searchable activity. You can pass the additional data in the <code><a href="../../../reference/android/app/SearchManager.html#APP_DATA">APP_DATA</a></code> <code><a href="../../../reference/android/os/Bundle.html">Bundle</a></code>, which is included in the <code><a href="../../../reference/android/content/Intent.html#ACTION_SEARCH">ACTION_SEARCH</a></code> intent.</p>

<p>To pass this kind of data to your searchable activity, override the <code><a href="../../../reference/android/app/Activity.html#onSearchRequested()">onSearchRequested()</a></code> method for the activity from which the user can perform a
search, create a <code><a href="../../../reference/android/os/Bundle.html">Bundle</a></code> with the additional data, and call <code><a href="../../../reference/android/app/Activity.html#startSearch(java.lang.String, boolean, android.os.Bundle, boolean)">startSearch()</a></code> to activate the search dialog.
For example:</p>

<pre>
&#64;Override
public boolean onSearchRequested() {
     Bundle appData = new Bundle();
     appData.putBoolean(SearchableActivity.JARGON, true);
     startSearch(null, false, appData, false);
     return true;
 }
</pre>

<p>Returning "true" indicates that you have successfully handled this callback event and
called <code><a href="../../../reference/android/app/Activity.html#startSearch(java.lang.String, boolean, android.os.Bundle, boolean)">startSearch()</a></code> to activate
the search dialog. Once the user submits a query, it's delivered to your
searchable activity along with the data you've added. You can extract the extra data from the <code><a href="../../../reference/android/app/SearchManager.html#APP_DATA">APP_DATA</a></code> <code><a href="../../../reference/android/os/Bundle.html">Bundle</a></code> to refine the search. For example:</p>

<pre>
Bundle appData = getIntent().getBundleExtra(SearchManager.APP_DATA);
if (appData != null) {
    boolean jargon = appData.getBoolean(SearchableActivity.JARGON);
}
</pre>

<p class="caution"><strong>Caution:</strong> Never call the <code><a href="../../../reference/android/app/Activity.html#startSearch(java.lang.String, boolean, android.os.Bundle, boolean)">startSearch()</a></code> method from outside
the <code><a href="../../../reference/android/app/Activity.html#onSearchRequested()">onSearchRequested()</a></code> callback method. To activate the search dialog
in your activity, always call <code><a href="../../../reference/android/app/Activity.html#onSearchRequested()">onSearchRequested()</a></code>. Otherwise, <code><a href="../../../reference/android/app/Activity.html#onSearchRequested()">onSearchRequested()</a></code> is not called and customizations (such as the addition of
<code>appData</code> in the above example) are missed.</p>



<h2 id="UsingSearchWidget">Using the Search Widget</h2>

<div class="figure" style="width:429px;margin:0">
  <img src="../../../images/ui/actionbar-actionview.png" alt="" />
  <p class="img-caption"><strong>Figure 2.</strong> The <code><a href="../../../reference/android/widget/SearchView.html">SearchView</a></code> widget as an "action view" in the Action Bar.</p>
</div>

<p>The <code><a href="../../../reference/android/widget/SearchView.html">SearchView</a></code> widget is available in Android 3.0 and higher. If
you're developing your application for Android 3.0 and have decided to use the search widget, we
recommend that you insert the search widget as an <a
href="../../../guide/topics/ui/actionbar.html#ActionView">action view in the Action Bar</a>,
instead of using the search dialog (and instead of placing the search widget in your activity
layout). For example, figure 2 shows the search widget in the Action Bar.</p>

<p>The search widget provides the same functionality as the search dialog. It starts the appropriate
activity when the user executes a search, and it can provide search suggestions and perform voice
search.</p>

<p class="note"><strong>Note:</strong> When you use the search widget as an action view, you
still might need to support using the search dialog, for cases in which the search widget does
not fit in the Action Bar. See the following section about <a href="#UsingBoth">Using both
the widget and the dialog</a>.</p>


<h3 id="ConfiguringWidget">Configuring the search widget</h3>

<p>After you've created a  <a href="#SearchableConfiguration">searchable configuration</a> and a <a
href="#SearchableActivity">searchable activity</a>, as discussed above, you need to enable assisted
search for each <code><a href="../../../reference/android/widget/SearchView.html">SearchView</a></code>. You can do so by calling <code><a href="../../../reference/android/widget/SearchView.html#setSearchableInfo(android.app.SearchableInfo)">setSearchableInfo()</a></code> and passing it the <code><a href="../../../reference/android/app/SearchableInfo.html">SearchableInfo</a></code> object that represents your searchable configuration.</p>

<p>You can get a reference to the <code><a href="../../../reference/android/app/SearchableInfo.html">SearchableInfo</a></code> by calling <code><a href="../../../reference/android/app/SearchManager.html#getSearchableInfo(android.content.ComponentName)">getSearchableInfo()</a></code> on <code><a href="../../../reference/android/app/SearchManager.html">SearchManager</a></code>.</p>

<p>For example, if you're using a <code><a href="../../../reference/android/widget/SearchView.html">SearchView</a></code> as an action view in the <a
href="../../../guide/topics/ui/actionbar.html">Action Bar</a>, you should enable the widget
during the <code><a href="../../../reference/android/app/Activity.html#onCreateOptionsMenu(android.view.Menu)">onCreateOptionsMenu()</a></code> callback:</p>

<pre>
&#64;Override
public boolean onCreateOptionsMenu(Menu menu) {
    // Inflate the options menu from XML
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.options_menu, menu);

    // Get the SearchView and set the searchable configuration
    SearchManager searchManager = (SearchManager) <code><a href="../../../reference/android/app/Activity.html#getSystemService(java.lang.String)">getSystemService</a></code>(Context.SEARCH_SERVICE);
    SearchView searchView = (SearchView) menu.findItem(R.id.menu_search).getActionView();
    searchView.setSearchableInfo(searchManager.getSearchableInfo(<code><a href="../../../reference/android/app/Activity.html#getComponentName()">getComponentName()</a></code>));
    searchView.setIconifiedByDefault(false); // Do not iconify the widget; expand it by default

    return true;
}
</pre>

<p>That's all you need. The search widget is now configured and the system will deliver search
queries to your searchable activity. You can also enable <a href="#SearchSuggestions">search
suggestions</a> for the search widget.</p>

<p class="note"><strong>Note:</strong> If you want to handle all user input yourself, you can do so
with some callback methods and event listeners. For more information, see the reference
documentation for <code><a href="../../../reference/android/widget/SearchView.html">SearchView</a></code> and its nested interfaces for the
appropriate event listeners.</p>

<p>For more information about action views in the Action Bar, read the <a
href="../../../guide/topics/ui/actionbar.html#ActionView">Action Bar</a> developer guide (which
includes sample code for adding a search widget as an action view).</p>


<h3 id="WidgetFeatures">Other search widget features</h3>

<p>The <code><a href="../../../reference/android/widget/SearchView.html">SearchView</a></code> widget allows for a few additional features you might
want:</p>

<dl>
  <dt>A submit button</dt>
  <dd>By default, there's no button to submit a search query, so the user must press the
"Return" key on the keyboard to initiate a search. You can add a "submit" button by calling
<code><a href="../../../reference/android/widget/SearchView.html#setSubmitButtonEnabled(boolean)">setSubmitButtonEnabled(true)</a></code>.</dd>
  <dt>Query refinement for search suggestions</dt>
  <dd>When you've enabled search suggestions, you usually expect users to simply select a
suggestion, but they might also want to refine the suggested search query. You can add a button
alongside each suggestion that inserts the suggestion in the search box for refinement by the
user, by calling <code><a href="../../../reference/android/widget/SearchView.html#setQueryRefinementEnabled(boolean)">setQueryRefinementEnabled(true)</a></code>.</dd>
  <dt>The ability to toggle the search box visibility</dt>
  <dd>By default, the search widget is "iconified," meaning that it is represented only by a
search icon (a magnifying glass), and expands to show the search box when the user touches it.
As shown above, you can show the search box by default, by calling <code><a href="../../../reference/android/widget/SearchView.html#setIconifiedByDefault(boolean)">setIconifiedByDefault(false)</a></code>. You can also
toggle the search widget appearance by calling <code><a href="../../../reference/android/widget/SearchView.html#setIconified(boolean)">setIconified()</a></code>.</dd>
</dl>

<p>There are several other APIs in the <code><a href="../../../reference/android/widget/SearchView.html">SearchView</a></code> class that allow you to
customize the search widget. However, most of them are used only when you handle all
user input yourself, instead of using the Android system to deliver search queries and display
search suggestions.</p>


<h3 id="UsingBoth">Using both the widget and the dialog</h3>

<p>If you insert the search widget in the Action Bar as an <a
href="../../../guide/topics/ui/actionbar.html#ActionView">action view</a>, and you enable it to
appear in the Action Bar "if there is room" (by setting <code>android:showAsAction="ifRoom"</code>), then there is a chance that the search widget will not appear
as an action view, but the menu item will appear in the overflow menu. For example, when your
application runs on a smaller screen, there might not be enough room in the Action Bar to display
the search widget along with other action items or navigation elements, so the menu item will
instead appear in the overflow menu. When placed in the overflow menu, the item works like an
ordinary menu item and does not display the action view (the search widget).</p>

<p>To handle this situation, the menu item to which you've attached the search widget should
activate the search dialog when the user selects it from the overflow menu. In order for it to do
so, you must implement <code><a href="../../../reference/android/app/Activity.html#onOptionsItemSelected(android.view.MenuItem)">onOptionsItemSelected()</a></code> to
handle the "Search" menu item and open the search dialog by calling <code><a href="../../../reference/android/app/Activity.html#onSearchRequested()">onSearchRequested()</a></code>.</p>

<p>For more information about how items in the Action Bar work and how to handle this situation, see
the <a href="../../../guide/topics/ui/actionbar.html">Action
Bar</a> developer guide.</p>

<p>Also see the <a
href="../../../resources/samples/SearchableDictionary/src/com/example/android/searchabledict/
SearchableDictionary.html">Searchable Dictionary</a> for an example implementation using
both the dialog and the widget.</p>



<h2 id="VoiceSearch">Adding Voice Search</h2>

<p>You can add voice search functionality to your search dialog or widget by adding the <code>android:voiceSearchMode</code> attribute to your searchable configuration. This adds a voice search
button that launches a voice prompt. When the user
has finished speaking, the transcribed search query is sent to your searchable
activity.</p>

<p>For example:</p>

<pre>
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/search_label"
    android:hint="@string/search_hint"
    <b>android:voiceSearchMode="showVoiceSearchButton|launchRecognizer"</b> >
&lt;/searchable>
</pre>

<p>The value <code>showVoiceSearchButton</code> is required to enable voice
search, while the second value, <code>launchRecognizer</code>, specifies that the voice search button
should launch a recognizer that returns the transcribed text to the searchable activity.</p>

<p>You can provide additional attributes to specify the voice search behavior, such
as the language to be expected and the maximum number of results to return. See the <a
href="searchable-config.html">Searchable Configuration</a> reference for more information about the
available attributes.</p>

<p class="note"><strong>Note:</strong> Carefully consider whether voice search is appropriate for
your application. All searches performed with the voice search button are immediately sent to
your searchable activity without a chance for the user to review the transcribed query. Sufficiently
test the voice recognition and ensure that it understands the types of queries that
the user might submit inside your application.</p>



<h2 id="SearchSuggestions">Adding Search Suggestions</h2>

<div class="figure" style="width:250px;margin:0">
<img src="../../../images/search/search-suggest-custom.png" alt="" height="417" />
<p class="img-caption"><strong>Figure 3.</strong> Screenshot of a search dialog with custom
search suggestions.</p>
</div>

<p>Both the search dialog and the search widget can provide search suggestions as the user
types, with assistance from the Android system. The system manages the list of suggestions and
handles the event when the user selects a suggestion.</p>

<p>You can provide two kinds of search suggestions:</p>

<dl>
  <dt>Recent query search suggestions</dt>
  <dd>These suggestions are simply words that the user previously used as search queries in
your application.
  <p>See <a href="adding-recent-query-suggestions.html">Adding Recent Query
Suggestions</a>.</p></dd>
  <dt>Custom search suggestions</dt>
  <dd>These are search suggestions that you provide from your own data source, to help users
immediately select the correct spelling or item they are searching for. Figure 3 shows an
example of custom suggestions for a dictionary application&mdash;the user can select a suggestion
to instantly go to the definition.
  <p>See <a href="adding-custom-suggestions.html">Adding Custom
Suggestions</a></p></dd>
</dl>


    </div>

  <a href="#top" style="float:right">&uarr; Go to top</a>
  
    <p><a href="index.html">&larr; Back to Search</a></p>
  
  </div>

<div id="footer">


  <div id="copyright">
    
  Except as noted, this content is licensed under <a
  href="http://www.apache.org/licenses/LICENSE-2.0">Apache 2.0</a>. 
  For details and restrictions, see the <a href="../../../license.html">
  Content License</a>.
  </div>
  <div id="build_info">
    
  Android 4.0&nbsp;r1 - 17 Oct 2011 18:17

  </div>

  <div id="footerlinks">
    
  <p>
    <a href="http://www.android.com/terms.html">Site Terms of Service</a> -
    <a href="http://www.android.com/privacy.html">Privacy Policy</a> -
    <a href="http://www.android.com/branding.html">Brand Guidelines</a>
  </p>
  </div>

</div> <!-- end footer -->

</div><!-- end doc-content -->

</div> <!-- end body-content --> 

<script type="text/javascript">
init(); /* initialize android-developer-docs.js */
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
var pageTracker = _gat._getTracker("UA-5831155-1");
pageTracker._trackPageview();
</script>

</body>
</html>



